From 917c36341613b59637c398e0c942d2f0ec0162af Mon Sep 17 00:00:00 2001 From: Behnam Esfahbod Date: Wed, 30 Aug 2017 18:10:13 -0700 Subject: [PATCH] [src/doc/book] Update 03-02-manifest.md from manifest.md --- src/doc/MIGRATION_MAP | 2 +- src/doc/book/src/03-02-manifest.md | 84 ++++++++++++++++++++---------- src/doc/manifest.md | 11 ++-- 3 files changed, 62 insertions(+), 35 deletions(-) diff --git a/src/doc/MIGRATION_MAP b/src/doc/MIGRATION_MAP index 85c7ed570..80cf26787 100644 --- a/src/doc/MIGRATION_MAP +++ b/src/doc/MIGRATION_MAP @@ -6,7 +6,7 @@ external-tools.md book/src/03-09-external-tools.md faq.md book/src/faq.md guide.md book/src/guide.md book/src/02-*.md index.md book/src/SUMMARY.md book/src/01-*.md -manifest.md +manifest.md book/src/03-02-manifest.md pkgid-spec.md policies.md source-replacement.md diff --git a/src/doc/book/src/03-02-manifest.md b/src/doc/book/src/03-02-manifest.md index 6068bb5a5..a5d25e77b 100644 --- a/src/doc/book/src/03-02-manifest.md +++ b/src/doc/book/src/03-02-manifest.md @@ -30,7 +30,7 @@ Versioning](http://semver.org/), so make sure you follow some basic rules: #### The `build` field (optional) -This field specifies a file in the repository which is a [build script][1] for +This field specifies a file in the project root which is a [build script][1] for building native code. More information can be found in the build script [guide][1]. @@ -52,7 +52,8 @@ Documentation links from specific hosts are blacklisted. Hosts are added to the blacklist if they are known to not be hosting documentation and are possibly of malicious intent e.g. ad tracking networks. URLs from the following hosts are blacklisted: -- rust-ci.org + +* rust-ci.org Documentation URLs from blacklisted hosts will not appear on crates.io, and may be replaced by docs.rs links. @@ -107,7 +108,7 @@ migration. #### The `publish` field (optional) The `publish` field can be used to prevent a package from being published to a -repository by mistake. +package registry (like *crates.io*) by mistake. ```toml [package] @@ -124,7 +125,7 @@ Cargo.toml with `[workspace]` upwards in the filesystem. ```toml [package] # ... -workspace = "path/to/root" +workspace = "path/to/workspace/root" ``` For more information, see the documentation for the workspace table below. @@ -142,15 +143,15 @@ There are a number of optional metadata fields also accepted under the # uploaded to crates.io (aka this is not markdown). description = "..." -# These URLs point to more information about the repository. These are +# These URLs point to more information about the package. These are # intended to be webviews of the relevant data, not necessarily compatible # with VCS tools and the like. documentation = "..." homepage = "..." repository = "..." -# This points to a file in the repository (relative to this `Cargo.toml`). The -# contents of this file are stored and indexed in the registry. +# This points to a file under the package root (relative to this `Cargo.toml`). +# The contents of this file are stored and indexed in the registry. readme = "..." # This is a list of up to five keywords that describe this crate. Keywords @@ -175,31 +176,47 @@ license = "..." license-file = "..." # Optional specification of badges to be displayed on crates.io. The badges -# currently available are Travis CI, Appveyor, and GitLab latest build status, -# specified using the following parameters: +# pertaining to build status that are currently available are Appveyor, CircleCI, +# GitLab, and TravisCI. Available badges pertaining to code test coverage are +# Codecov and Coveralls. There are also maintenance-related badges which state +# the issue resolution time, percent of open issues, and future maintenance +# intentions. [badges] -# Travis CI: `repository` in format "/" is required. -# `branch` is optional; default is `master` -travis-ci = { repository = "...", branch = "master" } + # Appveyor: `repository` is required. `branch` is optional; default is `master` # `service` is optional; valid values are `github` (default), `bitbucket`, and # `gitlab`. appveyor = { repository = "...", branch = "master", service = "github" } + +# Circle CI: `repository` is required. `branch` is optiona; default is `master` +circle-ci = { repository = "...", branch = "master" } + # GitLab: `repository` is required. `branch` is optional; default is `master` gitlab = { repository = "...", branch = "master" } -# Circle CI: `repository` is required. `branch` is optional; default is `master` -circle-ci = { repository = "...", branch = "master" } -# Is it maintained resolution time: `repository` is required. -is-it-maintained-issue-resolution = { repository = "..." } -# Is it maintained percentage of open issues: `repository` is required. -is-it-maintained-open-issues = { repository = "..." } + +# Travis CI: `repository` in format "/" is required. +# `branch` is optional; default is `master` +travis-ci = { repository = "...", branch = "master" } + # Codecov: `repository` is required. `branch` is optional; default is `master` # `service` is optional; valid values are `github` (default), `bitbucket`, and # `gitlab`. codecov = { repository = "...", branch = "master", service = "github" } + # Coveralls: `repository` is required. `branch` is optional; default is `master` # `service` is optional; valid values are `github` (default) and `bitbucket`. coveralls = { repository = "...", branch = "master", service = "github" } + +# Is it maintained resolution time: `repository` is required. +is-it-maintained-issue-resolution = { repository = "..." } + +# Is it maintained percentage of open issues: `repository` is required. +is-it-maintained-open-issues = { repository = "..." } + +# Maintenance: `status` is required Available options are `actively-developed`, +# `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer` +# and `deprecated`. +maintenance = { status = "..." } ``` The [crates.io](https://crates.io) registry will render the description, display @@ -446,23 +463,22 @@ members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] exclude = ["path1", "path/to/dir2"] ``` -Workspaces were added to Cargo as part [RFC 1525] and have a number of +Workspaces were added to Cargo as part of [RFC 1525] and have a number of properties: -* A workspace can contain multiple crates where one of them is the root crate. -* The root crate's `Cargo.toml` contains the `[workspace]` table, but is not +* A workspace can contain multiple crates where one of them is the *root crate*. +* The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not required to have other configuration. -* Whenever any crate in the workspace is compiled, output is placed next to the - root crate's `Cargo.toml`. -* The lock file for all crates in the workspace resides next to the root crate's - `Cargo.toml`. +* Whenever any crate in the workspace is compiled, output is placed in the + *workspace root*. i.e. next to the *root crate*'s `Cargo.toml`. +* The lock file for all crates in the workspace resides in the *workspace root*. * The `[patch]` and `[replace]` sections in `Cargo.toml` are only recognized - at the workspace root crate, they are ignored in member crates' manifests. + in the *root crate*'s manifest, and ignored in member crates' manifests. [RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md -The root crate of a workspace, indicated by the presence of `[workspace]` in its -manifest, is responsible for defining the entire workspace. All `path` +The *root crate* of a workspace, indicated by the presence of `[workspace]` in +its manifest, is responsible for defining the entire workspace. All `path` dependencies residing in the workspace directory become members. You can add additional packages to the workspace by listing them in the `members` key. Note that members of the workspaces listed explicitly will also have their path @@ -485,6 +501,18 @@ and also be a member crate of another workspace (contain `package.workspace`). Most of the time workspaces will not need to be dealt with as `cargo new` and `cargo init` will handle workspace configuration automatically. +#### Virtual Manifest + +In workspace manifests, if the `package` table is present, the workspace root +crate will be treated as a normal package, as well as a worksapce. If the +`package` table is not present in a worksapce manifest, it is called a *virtual +manifest*. + +When working with *virtual manifests*, package-related cargo commands, like +`cargo build`, won't be available anymore. But, most of such commands support +the `--all` option, will execute the command for all the non-virtual manifest in +the workspace. + #TODO: move this to a more appropriate place ### The project layout diff --git a/src/doc/manifest.md b/src/doc/manifest.md index 544b50665..482d9c764 100644 --- a/src/doc/manifest.md +++ b/src/doc/manifest.md @@ -108,7 +108,7 @@ migration. ## The `publish` field (optional) The `publish` field can be used to prevent a package from being published to a -package repository (like *crates.io*) by mistake. +package registry (like *crates.io*) by mistake. ```toml [package] @@ -175,7 +175,7 @@ license = "..." # (similar to the readme key). license-file = "..." -# Optional specification of badges to be displayed on crates.io. The badges +# Optional specification of badges to be displayed on crates.io. The badges # pertaining to build status that are currently available are Appveyor, CircleCI, # GitLab, and TravisCI. Available badges pertaining to code test coverage are # Codecov and Coveralls. There are also maintenance-related badges which state @@ -217,7 +217,6 @@ is-it-maintained-open-issues = { repository = "..." } # `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer` # and `deprecated`. maintenance = { status = "..." } - ``` The [crates.io](https://crates.io) registry will render the description, display @@ -520,7 +519,7 @@ If your project is an executable, name the main source file `src/main.rs`. If it is a library, name the main source file `src/lib.rs`. Cargo will also treat any files located in `src/bin/*.rs` as executables. If your -executable consist of more than just one source file, you might also use a directory +executable consists of more than just one source file, you might also use a directory inside `src/bin` containing a `main.rs` file which will be treated as an executable with a name of the parent directory. Do note, however, once you add a `[[bin]]` section ([see @@ -572,8 +571,8 @@ name = "foo" crate-type = ["staticlib"] ``` -You can build individual library examples with the command -`cargo build --example `. +You can build individual library examples with the command `cargo build +--example `. # Tests -- 2.30.2